                                    GEM(R)/3

                              Programmer's Toolkit

                                README.DOC  File

                                   March 1988


     This file contains information concerning the GEM/3 Programmer's 
     Toolkit for the IBM PC/XT/AT or PS/2 models.


     1 - The differences between GEM/3 Programmer's Toolkit and its
     previous version are:

         A. GEM/3 Programmer's Toolkit Release Note contains important
         supplemental information to your VDI/AES/RCS manuals.  Please
         refer to it whenever you use these manuals.

         B. The files INSTALL.APP, INSTALL.TXT, INSTALL.RSC are included
         to help the user install the GEM/3 Programmer's Toolkit.

         C. Large model binding and batch files are included.  The user can
         decide whether to install small model, large model, or both models.

         D. The Resource Construction Set (RCS.APP) includes a new icon editor
         that provides many convenient ways to create your icon or image.
         It can also scale your icon for different resolutions.  Both high
         and low resolution resources are now provided.

         E. The utility LMAP2SYM is also included. It is used to convert
         a large model map file generated by LINK to a sym file needed by
         GEMSID for symbolic debugging.  For those who use PLINK, PMAP2SYM
         is the corresponding utility.


     2 - The executable (.APP) versions of the demonstration programs supplied
     with this package have been assembled, compiled, and linked using
     the following tools:

        -  MASM v3.0
        -  LATTICE C Compiler v3.2
        -  LINK v3.05

     3 - To link a GEM application (not a GEM accessory), you may use
     the startup program and library supplied by your compiler,  if you
     know that your compiler generates code to free memory not used by
     your program.  Then link your program as follows, where the
     main routine's name is "main":  

       LINK startup+your_main+your_others,your_exe,your_map/m,library_files

     If your compiler does not free memory for you, you must use the
     startup programs TCS, PROSTART, and PROEND provided in this package 
     and use "GEMAIN" as your main routine's name. 

     For small model, use:

       LINK TCS+PROSTART+your_main+other_files+PROEND,your_exe,your_map

     For large model, use:

       LINK LTCL+LPROSTRT+your_main+other_files+LPROEND,your_exe,your_map

     If your compiler frees up memory for you, but you want to write a
     GEM accessory, use the following link statement:

       LINK TCS+ACCSTART+your_main+other_files+PROEND,your_exe,your_map

     4 - To use other compilers or other models, consider the following:

     If you use any .ASM file provided in this package, you may need
     to modify LARGE.MAC and some .ASM files for the following areas 
     in the segment defining statement:

     * segment name
     * class name
     * align type
     * combine type

     This ensures compatibility with your compiler's convention. 

     Lattice compiler V3.2 uses the following convention for code segments:

        MODEL    CLASS    GROUP    SEGMENT    TYPE

        SMALL    PROG     PGROUP    PROG      PUBLIC
        LARGE    PROG              name_PROG  PUBLIC

     Please refer to the compiler manual and Microsoft Macro Assembler
     Reference Manual as well.  Check the data segment convention too.

     For a long integer, the Lattice compiler returns a value in AX and 
     BX, with the high-order part in AX.  Modify the LONGASM.ASM file if 
     your compiler has a different convention.
 
     5 - Note that each of the batch files assemble and compile all
     modules required for the linking of your application.   Once you
     have assembled and compiled the bindings, you might find it useful
     to remove the commands that assemble and compile the bindings.
     This makes recreating your applications less time consuming.

     6 - The file SIDSAMPL.DOC is provided to demonstrate the use of
     SID in a sample debugging session.  GEMSID is an extended version
     of SID.  It makes use of additional commands specific to the
     graphics environment.  This file uses the Digital Research tools
     RASM86 and LINK86.  When you use GEMSID, you will probably be
     using MASM and LINK, since these are the tools for which we provide
     bindings.  SIDSAMPL.DOC does not demonstrate the use of the
     graphics capabilities of GEMSID.
